home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 301-325 / disk_319 / cnewssrc / cnews.orig.lzh / notebook / config < prev    next >
Text File  |  1989-06-27  |  6KB  |  164 lines
  1. .DA "18 Feb 1989"
  2. .TL
  3. Configuration Mechanisms in C News
  4. .AU
  5. Henry Spencer
  6. .AI
  7. Dept. of Zoology
  8. University of Toronto
  9. .SH
  10. Intro
  11. .LP
  12. There is an overall problem with news stuff in that some pathnames
  13. and such are site-specific.
  14. In C News this hits both shell files and C programs, the former a
  15. particular inconvenience because they are not compiled and hence can't
  16. easily pick it up from a library at compile time.
  17. It's easy to edit shell files, but there are too many of them for this
  18. to be very convenient.
  19. .LP
  20. Several mechanisms are needed to solve the entire problem..
  21. .SH
  22. Configuration Parameters
  23. .LP
  24. Although there are many things that theoretically could be site-specific,
  25. there are only a few that really crop up constantly,
  26. are highly likely to change,
  27. and have to be known to running code.
  28. Here's a tentative list, with internal names and common defaults:
  29. .TS
  30. lll.
  31. NEWSARTS    pathname of the article database    /usr/spool/news
  32. NEWSCTL    pathname of the control-file directory    /usr/lib/news
  33. NEWSBIN    pathname of the program directory    /usr/lib/newsbin
  34. NEWSPATH    shell PATH setting for news    /bin:/usr/bin
  35. NEWSUMASK    default umask for file creation    002
  36. NEWSMASTER    where to send mail about trouble    usenet
  37. NEWSCONFIG    see "Subst" section    /usr/lib/news/bin/config
  38. .TE
  39. .SH
  40. Environment Variables
  41. .LP
  42. All C News programs
  43. that care about configuration parameters are expected to look at
  44. environment variables with the same names as the parameters, and to
  45. use the environment values to override internal defaults.
  46. This is primarily aimed at testing and special purposes rather than
  47. production use, as there is a fundamental problem:
  48. the environment is insecure.
  49. The environment variables are nevertheless very useful.
  50. .LP
  51. There is a need for a canned interface to the environment variables,
  52. to simplify their use.
  53. There is also a requirement for centrally-set defaults for normal
  54. production use.
  55. These requirements are addressed differently for C and shell programs.
  56. .SH
  57. C Interface
  58. .LP
  59. \fILibcnews\fR provides a set of inquiry functions:
  60. .LP
  61. .RS
  62. .IP "char *fullartfile(char *name);"
  63. Returns a full pathname for the NEWSARTS-relative file \fIname\fR;
  64. if \fIname\fR is NULL, returns the value of NEWSARTS.
  65. .IP "char *ctlfile(char *name);"
  66. Returns a full pathname for the NEWSCTL-relative file \fIname\fR;
  67. if \fIname\fR is NULL, returns the value of NEWSCTL.
  68. .IP "char *binfile(char *name);"
  69. Returns a full pathname for the NEWSBIN-relative file \fIname\fR;
  70. if \fIname\fR is NULL, returns the value of NEWSBIN.
  71. .IP "char *newspath(void);"
  72. Returns the value of the NEWSPATH parameter.
  73. .IP "int newsumask(void);"
  74. Returns the value of the NEWSUMASK parameter.
  75. .IP "char *newsmaster(void);"
  76. Returns the value of NEWSMASTER.
  77. .RE
  78. .LP
  79. Functions which return string values return pointers to areas which they
  80. may later re-use, so the values should be copied if they are to persist
  81. past later calls.
  82. There is also a function \fIartfile\fR which returns a relative pathname,
  83. as a special-purpose optimization,
  84. and a function \fIcd\fR which does a \fIchdir\fR and notes the location
  85. for future use by \fIartfile\fR.
  86. .LP
  87. The first inquiry function to be invoked automatically initializes
  88. their internal housekeeping.
  89. Against the possibility of malicious setting of environment variables,
  90. if any environment variables are in fact present to override default
  91. values, and at least one value in fact differs from the default,
  92. this initialization includes a call to a function the user must supply:
  93. .LP
  94. .RS
  95. .IP "void unprivileged(void);"
  96. Drop any special powers that should not be available to a normal user
  97. program,
  98. e.g. those obtained by set-uid bit.
  99. .RE
  100. .LP
  101. Programs that do not use the set-uid bit can normally have a null
  102. implementation of \fIunprivileged\fR, but to encourage thought about
  103. the matter this is \fInot\fR provided as a default.
  104. .LP
  105. Suitable external declarations for all these functions can be found
  106. in the include file \fIconfig.h\fR in the C News include directory.
  107. .SH
  108. Shell interface
  109. .LP
  110. All shell files that want to know configuration parameters should
  111. execute NEWSCTL/bin/config using the `.' command;
  112. it sets shell variables with the same names as the parameters.
  113. Note that it does not export these variables, so subordinate shell
  114. files need to pick up \fIconfig\fR themselves.
  115. This is to preserve the property that subordinate programs see environment
  116. variables set only if the user set them.
  117. .SH
  118. Subst
  119. .LP
  120. The alert mind will have noticed a circularity in the previous section:
  121. it's not possible to find NEWSCTL/bin/config until one knows where NEWSCTL is.
  122. There are also occasional annoyances in that documentation and such wants
  123. to know the local defaults, and can't get them from either the C or shell
  124. interface.
  125. Hence the use of \fIsubst\fR.
  126. .LP
  127. \fISubst\fR does substitutions into source files (including shell files)
  128. in such a way that it is not necessary to maintain two versions of the file.
  129. In the top-level directory of the C News sources are four files:
  130. \fIsubst\fR itself, the \fIsubstitutions\fR file defining the values of
  131. the configuration parameters, and \fIsubst.hs\fR and \fIsubst.gc\fR,
  132. which are lists of files (relative to the top-level source directory)
  133. that need substitutions done.
  134. (The use of two `list' files reflects C News's dual authorship.)
  135. See the \fIsubst\fR(1) manual page for the gory details of the syntax.
  136. The only C program affected is the configuration-inquiry part of the
  137. library, but all shell files that need any of the configuration parameters
  138. need to be in one of the lists.
  139. .SH
  140. Program startup
  141. .LP
  142. As a result of all this, a C program which needs to know a configuration
  143. parameter simply calls the appropriate inquiry function,
  144. and is prepared for a return call to \fIunprivileged\fR.
  145. A shell program has to do a bit more work; it should start with something
  146. on the order of:
  147. .DS
  148. #! /bin/sh
  149. # foobar \- does foo, bar, and bletch
  150.  
  151. # =()<. ${NEWSCONFIG\-@<NEWSCONFIG>@}>()=
  152. . ${NEWSCONFIG\-/usr/lib/news/bin/config}
  153.  
  154. PATH=$NEWSCTL/bin:$NEWSBIN/xxx:$NEWSBIN:$NEWSPATH ; export PATH
  155. umask $NEWSUMASK
  156. .DE
  157. (A prototype for this is in conf/proto.sh.)
  158. (See an accompanying document for the logic of the PATH setting.)
  159. The NEWSCONFIG configuration parameter specifies the location of the
  160. configurer shell program, which is then executed to set up the rest
  161. of the parameters.
  162. The reason for doing it this way is to ensure that new parameters
  163. can be added without having to change every shell file.
  164.